Rate Limits

Paths are relative to https://api.clocktower.finance.

Limits are per identity (not one shared pool for all users). REST and MCP share these identities: a developer key used on both surfaces counts against the same buckets.

Lane	Identity
Free	Client IP
Developer	API key (ctk_…)

Default limits (approx.)

Lane	Auth	Global	Expensive	Subgraph / day	Prepare / readiness	All requests / day
Free	None	20 rpm	3 rpm	100	2/min · 20/day	500
Developer	Bearer ctk_…	80 rpm	40 rpm	3,000	5/min · 100/day	5,000

Canonical numbers: GET /catalog → access.rest.*.limits (writeRpm, writeDaily, dailyTotalRequests, …). MCP tool calls use the same free and developer figures.

Rate buckets

• Global RPM — most requests
• Expensive RPM — subgraph-heavy / discovery-style GETs
• Subgraph daily — expensive routes that hit The Graph
• Write RPM — POST /prepare/*, POST /check_subscribe_readiness, and POST /check_remit_readiness
• Write daily — same set, per UTC day (protects shared Alchemy simulation cost)
• Daily total — every REST request and MCP tool call that day for that identity

A prepare call consumes write RPM, write daily, and daily total.

REST POST /check_subscribe_readiness_by_id is not in the write bucket (cheap / global RPM only — it does not run on-chain simulation). The MCP tool check_subscribe_readiness_by_id does consume the write/readiness bucket.

MCP prepare_* tools and the other readiness tools (check_subscribe_readiness, check_remit_readiness) use the same write buckets as the matching REST routes.

Why prepare is capped tightly

Full prepare runs on-chain simulation and gas estimation. The server never relays the transaction, but the dry-run still costs shared RPC. Free and developer tiers are for exploration and reads; production write volume should use the SDK with your own RPC.

Free tier notes

• Cross-account and provider reads allowed under the expensive bucket
• Search: first ≤ 10; no includeDetails=true

Developer tier notes

• Higher read and discovery limits than free
• Search: first ≤ 25; includeDetails allowed

• Invalid/revoked keys → 401, not free-tier fallback

Exceeding a limit

HTTP 429 with code: RATE_LIMITED, lane, Retry-After, and an upgradeHint. Response header X-Clocktower-Lane shows the lane that was applied.

Machine-readable catalog

GET /catalog returns the full route manifest and live tier limits. See Catalog.

Edge protections

Production deployments may also use Cloudflare edge rules (rate limiting, WAF, bot management) on top of application buckets.